<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- 
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License. 
-->
<html>
<head>
    <link type="text/css" rel="stylesheet" href="https://struts.apache.org/css/default.css">
    <style type="text/css">
        .dp-highlighter {
            width:95% !important;
        }
    </style>
    <style type="text/css">
        .footer {
            background-image:      url('https://cwiki.apache.org/confluence/images/border/border_bottom.gif');
            background-repeat:     repeat-x;
            background-position:   left top;
            padding-top:           4px;
            color:                 #666;
        }
    </style>
    <link href='https://struts.apache.org/highlighter/style/shCoreStruts.css' rel='stylesheet' type='text/css' />
    <link href='https://struts.apache.org/highlighter/style/shThemeStruts.css' rel='stylesheet' type='text/css' />
    <script src='https://struts.apache.org/highlighter/js/shCore.js' type='text/javascript'></script>
    <script src='https://struts.apache.org/highlighter/js/shBrushPlain.js' type='text/javascript'></script>
    <script src='https://struts.apache.org/highlighter/js/shBrushXml.js' type='text/javascript'></script>
    <script src='https://struts.apache.org/highlighter/js/shBrushJava.js' type='text/javascript'></script>
    <script src='https://struts.apache.org/highlighter/js/shBrushJScript.js' type='text/javascript'></script>
    <script src='https://struts.apache.org/highlighter/js/shBrushGroovy.js' type='text/javascript'></script>
    <script src='https://struts.apache.org/highlighter/js/shBrushBash.js' type='text/javascript'></script>
    <script type="text/javascript">
        SyntaxHighlighter.defaults['toolbar'] = false;
        SyntaxHighlighter.all();
    </script>
    <script type="text/javascript" language="javascript">
        var hide = null;
        var show = null;
        var children = null;

        function init() {
            /* Search form initialization */
            var form = document.forms['search'];
            if (form != null) {
                form.elements['domains'].value = location.hostname;
                form.elements['sitesearch'].value = location.hostname;
            }

            /* Children initialization */
            hide = document.getElementById('hide');
            show = document.getElementById('show');
            children = document.all != null ?
                    document.all['children'] :
                    document.getElementById('children');
            if (children != null) {
                children.style.display = 'none';
                show.style.display = 'inline';
                hide.style.display = 'none';
            }
        }

        function showChildren() {
            children.style.display = 'block';
            show.style.display = 'none';
            hide.style.display = 'inline';
        }

        function hideChildren() {
            children.style.display = 'none';
            show.style.display = 'inline';
            hide.style.display = 'none';
        }
    </script>
    <title>ActionMapper</title>
</head>
<body onload="init()">
<table border="0" cellpadding="2" cellspacing="0" width="100%">
    <tr class="topBar">
        <td align="left" valign="middle" class="topBarDiv" align="left" nowrap>
            &nbsp;<a href="home.html">Home</a>&nbsp;&gt;&nbsp;<a href="guides.html">Guides</a>&nbsp;&gt;&nbsp;<a href="core-developers-guide.html">Core Developers Guide</a>&nbsp;&gt;&nbsp;<a href="actionmapper.html">ActionMapper</a>
        </td>
        <td align="right" valign="middle" nowrap>
            <form name="search" action="https://www.google.com/search" method="get">
                <input type="hidden" name="ie" value="UTF-8" />
                <input type="hidden" name="oe" value="UTF-8" />
                <input type="hidden" name="domains" value="" />
                <input type="hidden" name="sitesearch" value="" />
                <input type="text" name="q" maxlength="255" value="" />
                <input type="submit" name="btnG" value="Google Search" />
            </form>
        </td>
    </tr>
</table>

<div id="PageContent">
    <div class="pageheader" style="padding: 6px 0px 0px 0px;">
        <!-- We'll enable this once we figure out how to access (and save) the logo resource -->
        <!--img src="/wiki/images/confluence_logo.gif" style="float: left; margin: 4px 4px 4px 10px;" border="0"-->
        <div style="margin: 0px 10px 0px 10px" class="smalltext">Apache Struts 2 Documentation</div>
        <div style="margin: 0px 10px 8px 10px"  class="pagetitle">ActionMapper</div>

        <div class="greynavbar" align="right" style="padding: 2px 10px; margin: 0px;">
            <a href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=14128">
                <img src="https://cwiki.apache.org/confluence/images/icons/notep_16.gif"
                     height="16" width="16" border="0" align="absmiddle" title="Edit Page"></a>
            <a href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=14128">Edit Page</a>
            &nbsp;
            <a href="https://cwiki.apache.org/confluence/pages/listpages.action?key=WW">
                <img src="https://cwiki.apache.org/confluence/images/icons/browse_space.gif"
                     height="16" width="16" border="0" align="absmiddle" title="Browse Space"></a>
            <a href="https://cwiki.apache.org/confluence/pages/listpages.action?key=WW">Browse Space</a>
            &nbsp;
            <a href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=WW&fromPageId=14128">
                <img src="https://cwiki.apache.org/confluence/images/icons/add_page_16.gif"
                     height="16" width="16" border="0" align="absmiddle" title="Add Page"></a>
            <a href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=WW&fromPageId=14128">Add Page</a>
            &nbsp;
            <a href="https://cwiki.apache.org/confluence/pages/createblogpost.action?spaceKey=WW&fromPageId=14128">
                <img src="https://cwiki.apache.org/confluence/images/icons/add_blogentry_16.gif"
                     height="16" width="16" border="0" align="absmiddle" title="Add News"></a>
            <a href="https://cwiki.apache.org/confluence/pages/createblogpost.action?spaceKey=WW&fromPageId=14128">Add News</a>
        </div>
    </div>

    <div class="pagecontent">
        <div class="wiki-content">
            <div id="ConfluenceContent"><p><style type="text/css">/*<![CDATA[*/
div.rbtoc1440488860740 {padding: 0px;}
div.rbtoc1440488860740 ul {list-style: disc;margin-left: 0px;}
div.rbtoc1440488860740 li {margin-left: 0px;padding-left: 0px;}

/*]]>*/</style></p><div class="toc-macro rbtoc1440488860740">
<ul class="toc-indentation"><li><a shape="rect" href="#ActionMapper-Description">Description</a></li><li><a shape="rect" href="#ActionMapper-DefaultActionMapper">DefaultActionMapper</a>
<ul class="toc-indentation"><li><a shape="rect" href="#ActionMapper-Methodprefix">Method prefix</a></li><li><a shape="rect" href="#ActionMapper-Actionprefix">Action prefix</a></li></ul>
</li><li><a shape="rect" href="#ActionMapper-CustomActionMapper">Custom ActionMapper</a></li><li><a shape="rect" href="#ActionMapper-CompositeActionMapper">CompositeActionMapper</a></li><li><a shape="rect" href="#ActionMapper-PrefixBasedActionMapper">PrefixBasedActionMapper</a></li><li><a shape="rect" href="#ActionMapper-ActionMapperandActionMappingobjects">ActionMapper and ActionMapping objects</a>
<ul class="toc-indentation"><li><a shape="rect" href="#ActionMapper-Customize">Customize</a></li></ul>
</li><li><a shape="rect" href="#ActionMapper-Next:ActionProxy&amp;ActionProxyFactory">Next: Action Proxy &amp; ActionProxy Factory</a></li></ul>
</div><h2 id="ActionMapper-Description">Description</h2><p></p><p></p><p>
The ActionMapper interface provides a mapping between HTTP requests and action invocation requests and vice-versa.
</p>

<p></p><p>
When given an HttpServletRequest, the ActionMapper may return null if no action invocation request matches,
or it may return an ActionMapping that describes an action invocation for the framework to try.
</p>

<p></p><p>
The ActionMapper is not required to guarantee that the ActionMapping returned be a real action or otherwise
ensure a valid request.
Accordingly, most ActionMappers do not need to consult the Struts configuration
just to determine if a request should be mapped.
</p>

<p></p><p>
Just as requests can be mapped from HTTP to an action invocation, the opposite is true as well.
However, because HTTP requests (when shown in HTTP responses) must be in String form,
a String is returned rather than an actual request object.
</p><h2 id="ActionMapper-DefaultActionMapper">DefaultActionMapper</h2><p>By default, the DefaultActionMapper is used:</p><p></p><p>
Default action mapper implementation, using the standard *.[ext] (where ext
usually "action") pattern. The extension is looked up from the Struts
configuration key <b>struts.action.extension</b>.
</p>

<p></p><p>
To help with dealing with buttons and other related requirements, this
mapper (and other ActionMappers, we hope) has the ability to name a
button with some predefined prefix and have that button name alter the
execution behaviour. The four prefixes are:
</p>

<p></p><ul><li>Method prefix - <i>method:default</i></li><li>Action prefix - <i>action:dashboard</i></li></ul>

<p></p><p>
In addition to these four prefixes, this mapper also understands the
action naming pattern of <i>foo!bar</i> in either the extension form (eg:
foo!bar.action) or in the prefix form (eg: action:foo!bar). This syntax tells
this mapper to map to the action named <i>foo</i> and the method <i>bar</i>.
</p><h3 id="ActionMapper-Methodprefix">Method prefix</h3><p></p><p></p><p>
With method-prefix, instead of calling baz action's execute() method (by
default if it isn't overriden in struts.xml to be something else), the baz
action's anotherMethod() will be called. A very elegant way determine which
button is clicked. Alternatively, one would have submit button set a
particular value on the action when clicked, and the execute() method decides
on what to do with the setted value depending on which button is clicked.
</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="brush: xml; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[
&lt;s:form action=&quot;baz&quot;&gt;
    &lt;s:textfield label=&quot;Enter your name&quot; name=&quot;person.name&quot;/&gt;
    &lt;s:submit value=&quot;Create person&quot;/&gt;
    &lt;s:submit method=&quot;anotherMethod&quot; value=&quot;Cancel&quot;/&gt;
&lt;/s:form&gt;
]]></script>
</div></div><h3 id="ActionMapper-Actionprefix">Action prefix</h3><p></p><p></p><p>
With action-prefix, instead of executing baz action's execute() method (by
default if it isn't overridden in struts.xml to be something else), the
anotherAction action's execute() method (assuming again if it isn't overridden
with something else in struts.xml) will be executed.
</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="brush: xml; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[
&lt;s:form action=&quot;baz&quot;&gt;
    &lt;s:textfield label=&quot;Enter your name&quot; name=&quot;person.name&quot;/&gt;
    &lt;s:submit value=&quot;Create person&quot;/&gt;
    &lt;s:submit action=&quot;anotherAction&quot; value=&quot;Cancel&quot;/&gt;
&lt;/s:form&gt;
]]></script>
</div></div><h2 id="ActionMapper-CustomActionMapper">Custom ActionMapper</h2><p>You can define your own ActionMapper by implementing <code>org.apache.struts2.dispatcher.mapper.ActionMapper</code> then configuring Struts 2 to use the new class in struts.xml</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">&lt;bean type="org.apache.struts2.dispatcher.mapper.ActionMapper" name="mymapper" class="com.mycompany.myapp.MyActionMapper" /&gt;
&lt;constant name="struts.mapper.class" value="mymapper" /&gt;
</pre>
</div></div><p>Possible uses of the ActionMapper include defining your own, cleaner namespaces, such as URLs like <strong>/person/1</strong>, which would be similar to a request to <strong>/getPerson.action?personID=1</strong> using the DefaultActionMapper.</p><h2 id="ActionMapper-CompositeActionMapper">CompositeActionMapper</h2><p>A composite action mapper that is capable of delegating to a series of <a shape="rect" href="actionmapper.html">ActionMapper</a> if the former failed to obtained a valid <a shape="rect" class="createlink" href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=WW&amp;title=ActionMapping&amp;linkCreation=true&amp;fromPageId=14128">ActionMapping</a> or uri.</p><p>It is configured through <a shape="rect" href="strutsxml.html">struts.xml</a>. For example, with the following entries in struts.xml</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">&lt;constant name="struts.mapper.class" value="composite" /&gt;
&lt;constant name="struts.mapper.composite" value="struts,restful,restful2" /&gt;
</pre>
</div></div><p>When <code>CompositeActionMapper#getMapping(HttpServletRequest, ConfigurationManager)</code> or <code>CompositeActionMapper#getUriFromActionMapping(ActionMapping)</code> is invoked, <code>CompositeActionMapper</code> would go through these <a shape="rect" href="actionmapper.html">ActionMapper</a>s in sequence starting from <a shape="rect" href="actionmapper.html">ActionMapper</a> identified by <code>struts.mapper.composite.1</code>, followed by <code>struts.mapper.composite.2</code> and finally <code>struts.mapper.composite.3</code> (in this case) until either one of the <a shape="rect" href="actionmapper.html">ActionMapper</a> return a valid result (not null) or it runs out of <a shape="rect" href="actionmapper.html">ActionMapper</a> in which case it will just return null for both <code>CompositeActionMapper#getMapping(HttpServletRequest, ConfigurationManager)</code> and <code>CompositeActionMapper#getUriFromActionMapping(ActionMapping)</code> methods.</p><p>For example with the following in struts.xml:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">&lt;constant name="struts.mapper.class" value="composite" /&gt;
&lt;constant name="struts.mapper.composite" value="struts,restful" /&gt;
</pre>
</div></div><p><code>CompositeActionMapper</code> will be configured with 2 ActionMapper, namely "struts" which is <code>org.apache.struts2.dispatcher.mapper.DefaultActionMapper</code> and "restful" which is <code>org.apache.struts2.dispatcher.mapper.RestfulActionMapperRestfulActionMapper</code>. <code>CompositeActionMapper</code> would consult each of them in order described above.</p><h2 id="ActionMapper-PrefixBasedActionMapper">PrefixBasedActionMapper</h2><p></p><p></p><p>
A prefix based action mapper that is capable of delegating to other ActionMappers based on the request's prefix.<br clear="none">
It is configured through struts.xml<br clear="none">
For example, with the following entries in struts.properties
</p>

<p></p><pre>
&lt;constant name="struts.mapper.class" value="org.apache.struts2.dispatcher.mapper.PrefixBasedActionMapper"/&gt;
&lt;constant name="struts.mapper.prefixMapping" value="/communities:pseudoRestful,/communityTags:pseudoRestful,/events:pseudoRestful,/mediaList:pseudoRestful,/users:pseudoRestful,/community:struts,/communityTag:struts,/event:struts,/media:struts,/user:struts,:struts"/&gt;
</pre>

<p></p><p>
When {@link PrefixBasedActionMapper#getMapping(HttpServletRequest, ConfigurationManager)} or
PrefixBasedActionMapper#getUriFromActionMapping(ActionMapping) is invoked,
PrefixBasedActionMapper will check each possible prefix (url prefix terminating just before a /) to find the most specific ActionMapper that returns a mapping when asked to map the request.  If none are found, null is returned for both
{@link PrefixBasedActionMapper#getMapping(HttpServletRequest, ConfigurationManager)} and
PrefixBasedActionMapper#getUriFromActionMapping(ActionMapping) methods.
</p>
<h4 id="ActionMapper-PrefixBasedActionProxyFactory">PrefixBasedActionProxyFactory</h4><p></p><p></p><p>
Prefix based factory should be used with org.apache.struts2.dispatcher.mapper.PrefixBasedActionMapper
to use appropriate com.opensymphony.xwork2.ActionProxyFactory connected with given
org.apache.struts2.dispatcher.mapper.ActionMapper
</p>

<p></p><p>
Add below entry to struts.xml to enable the factory:
</p>

<p></p><pre>
&lt;constant name="struts.actionProxyFactory" value="prefix"/&gt;
</pre>

<p></p><p>
The factory will use the same set of patterns as defined with:
</p>

<p></p><pre>
&lt;constant name="struts.mapper.prefixMapping" value="..."/&gt;
</pre><h2 id="ActionMapper-ActionMapperandActionMappingobjects">ActionMapper and ActionMapping objects</h2><p>The ActionMapper fetches the ActionMapping object corresponding to a given request. Essentially, the ActionMapping is a data transfer object that collects together details such as the Action class and method to execute. The mapping is utilized by the Dispatcher and various user interface components. It is customizable through <code>struts.mapper.class</code> entry in <code>struts.properties</code> or <code>struts.xml</code>. Note that the value of this constant is the name of the bean of the new mapper.</p><h3 id="ActionMapper-Customize">Customize</h3><div class="confluence-information-macro confluence-information-macro-warning"><span class="aui-icon aui-icon-small aui-iconfont-error confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>Custom ActionMapper must implement ActionMapper interface and have a default constructor.</p></div></div><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">&lt;bean type="org.apache.struts2.dispatcher.mapper.ActionMapper" name="mymapper" class="com.mycompany.myapp.MyActionMapper" /&gt;
&lt;constant name="struts.mapper.class" value="mymapper" /&gt;
</pre>
</div></div><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">public class MyCustomActionMapper implements ActionMapper {
  public ActionMapping getMapping(HttpServletRequest request,
                                  ConfigurationManager configManager) {
    ....
  }

  public String getUriFromActionMapping(ActionMapping mapping) {
    ....
  }
}
</pre>
</div></div><p><img class="emoticon emoticon-light-on" src="https://cwiki.apache.org/confluence/s/en_GB/5982/f2b47fb3d636c8bc9fd0b11c0ec6d0ae18646be7.1/_/images/icons/emoticons/lightbulb_on.png" data-emoticon-name="light-on" alt="(lightbulb)"> See also: <a shape="rect" href="restfulactionmapper.html">RestfulActionMapper</a></p><h2 id="ActionMapper-Next:ActionProxy&amp;ActionProxyFactory">Next: <a shape="rect" href="action-proxy-actionproxy-factory.html">Action Proxy &amp; ActionProxy Factory</a></h2></div>
        </div>

                    <div class="tabletitle">
                Children
            <span class="smalltext" id="show" style="display: inline;">
              <a href="javascript:showChildren()">Show Children</a></span>
            <span class="smalltext" id="hide" style="display: none;">
              <a href="javascript:hideChildren()">Hide Children</a></span>
            </div>
            <div class="greybox" id="children" style="display: none;">
                                                    $page.link($child)
                    <span class="smalltext">(Apache Struts 2 Documentation)</span>
                    <br>
                            </div>
        
    </div>
</div>
<div class="footer">
    Generated by CXF SiteExporter
</div>
</body>
</html>
